Software 2000

home *** CD-ROM | disk | FTP | other *** search

/ Software 2000 / Software 2000 Volume 1 (Disc 1 of 2).iso / utilities / u268.dms / in.adf / FRQLIB / programming.run / Programming / kd_freq.doc < prev next >

Wrap

Text File | 1992-01-22 | 22.3 KB | 834 lines

kd_freq.library Release 3.02 --------------- ------------ By: Khalid Aldoseri 'kd_freq.library' is a standard Amiga shared library. Its main function is to call up a file requester from any program so that the user can select a file. To open the library, use OpenLibrary() like any other normal Amiga library. The programming package contains the following files: kd_freq.doc This file. KDBase.h C include file. Glue.asm C glue code for Manx/Lattice. KDBase.i Asm include file. protos.h Lattice #pragmas Look at test.c for the exact opening procedure. You will need to assemble and link glue.asm along with your own object files or use the Lattice protos. e.g. for Manx: cc +l test.c as glue.asm ln test.o glue.o -lc32 AutoDocs: ------------------------------------------------------------------------------ kd_freq.library/NewFReq NAME NewFReq - bring up a file requester and obtain a file name. SYNOPSIS result = NewFReq(fr); D0 A0 struct FRequest *fr; char *result; FUNCTION Accepts a pointer to a FRequest structure and calls up the file requester. The FRequest structure contains several arguments that NewFReq() uses. Specifically a default directory name, default file name, and a default pattern (standard AmigaDOS wildcard pattern) and returns a selected directory, selected file name, and last pattern used in the same entries in struct FRequest that were used to call the requester. The CreateFRequest() call is used to allocate and initialize the FRequest structure. The FRequest structure contains the following: struct FRequest { struct Screen *screen; UBYTE *reqtitle; UBYTE *filename; UBYTE *directory; UBYTE *fullname; UBYTE *pattern; ULONG flags; struct ExtraData *extras; }; fr->screen a pointer to a Screen structure. This defines the screen the FR must show up on. If NULL then it defaults to the Workbench screen. fr->reqtitle The text that will appear as the title of the FR. fr->filename The default filename that will appear in the File gadget when the FR comes up. This will also contain the selected filename when the call returns. fr->directory The default directory that will appear in the Path gadget when the FR comes up. This will also contain the selected directory when the call returns. fr->fullname This is a string that is filled in by the NewFReq() call if it is successful. This contains the full path to the file, i.e. directory+filename. It is NULL if the FR failed or was cancelled. The NewFReq() call returns either a pointer to this string if successful, or NULL. fr->pattern The default wildcard pattern that will appear in the Show gadget when the FR comes up. This will also contain the last selected Show pattern. fr->flags is a set of flags that control the operation of the FR. These are described below. fr->extras a pointer to a Struct ExtraData, as defined below. File Requester Flags: --------------------- FR_NOINFO Do not show any file that ends with <.info>. The user can change this setting later by clicking on the 'I' gadget. (automatically set by CreateFRequest() as FR_STDFLAGS) FR_NORESIZE Do not allow the user to resize the FR. FR_NOTITLEBAR Do not show the close window gadget, the drag bar, or the front/back gadgets. The title still gets displayed. This makes the FR non-movable. This also automatically triggers FR_NORESIZE. If you don't provide a title the file list will resize and fill in the empty space. FR_AUTOPOSITION Tells the FR to decide where it wants to come up on its own. (i.e. ignore LeftEdge and TopEdge) (automatically set by CreateFRequest() as FR_STDFLAGS) FR_AUTOSIZE Tells the FR to decide its size on its own. (i.e. ignore Width and Height) (automatically set by CreateFRequest() as FR_STDFLAGS) FR_OKTEXT Tells the FR that we specified an alternate OK text in 'extras->oktext'. FR_CANCELTEXT Tells the FR that we specified an alternate 'Cancel' text in 'extras->canceltext'. FR_DUALWILD When you set this flag, the wildcard pattern you provide in 'pattern' is fixed and is applied to all files in the FR. The user then gets a second wildcard in the Wildcard gadget. (this defauls to #?). In essence, this allows you to specify a pattern that will appply to ALL the FR, no matter what the user selects as a wildcard. The user's wildcard is applied to a file after it passes from the first wildcard. FR_FRONTSCREEN Forces the FR to come up on the front screen. FR_NOTEXTSHADOW Turns off the text shadowing in all of the FR. FR_NEWFONT Tells the FR to use a different font than the standard Topaz 8. This can be any fixed spacing font from 5 to 16 in size. NO sanity checking is done on the font size. It is up to you to see how the font looks like. The FR will rescale everything to suit the new font. You need to provide a pointer to a TextFont structure in extras->NewFont. Make sure you clear FR_SCREENFONT if you set this. FR_SCREENFONT As above, but uses the current font on the screen the FR will show up on. This always overrides FR_NEWFONT. (automatically set by CreateFRequest() as FR_STDFLAGS) FR_REPLACEIMAGES Replaces the standard images in the FR with the users's own. The ExtraData struct below shows where to place each pointer. You can use any depth of bitplanes as long as they match the same width/height as the original gadgets. Be creative! Note that the size of the imagery changes with the requested font size. FR_EXTENDEDSELECT Old flag.. use FR_SELECTLIST instead. FR_INVERTLOOK Set this flag for an 'inverted' look for the file list. This is intended for use with 'save' calls so that the user gets a visual difference between save and load requesters. FR_HIDEWILD Set this flag and point extras.Hide to a character string of at least 32 bytes. This should contain the default wildcard pattern to Hide. i.e. any file matching this wildcard will not be shown in the file list. (automatically set by CreateFRequest() as FR_STDFLAGS) FR_NEWLOOK If you set this flag the FR will change the way it looks to make it match the look of Intuition 2.0 and above. This is automatically set if Intuition's version number is 36 or more. You should set this flag if you know that you are running under 2.0 or above. The automatic enable might be removed in a later version. FR_NONEWLOOK Disables the automatic enabling of FR_NEWLOOK. FR_SELECTLIST Enable the Select List mode. Read the section on the Select List below. FR_SLSHOWNAMES Read the section on Select List below. FR_KEEPBUFFERS Enables the Keep Buffer feature. Read section below on 'Keep Buffers'. FR_EXTRABUTTONS Allows you to define an extra gadget for the user to click on. You can define the gadget's text, and a function that will be called when the gadget is clicked on. Read the 'ExtraButton' section below for details on usage. These flags are defined in KDBase.h. You can OR any of these flags together. There are no restrictions on which flags can be or'd with others. The ExtraData structure: ------------------------ struct ExtraData { struct Image *UpArrow; /* replacement image for Up Arrow */ struct Image *DnArrow; /* replacement image for Down Arrow */ struct Image *DiskNormal; /* replacement image for Disks */ struct Image *DiskSelected; /* replacement select image for Disks */ struct Image *SizeStrip; /* private... do not use. */ UBYTE *oktext; /* text to be used as OK text */ UBYTE *canceltext; /* text to be used as CANCEL text */ USHORT LeftEdge,TopEdge,Width,Height; struct TextFont *NewFont; /* New Font to use instead of Topaz 8 */ struct FileList *ExtendedList; /* Always set to NULL at first call. */ /* If FR_EXTENDEDSELECT is set, this will */ /* return a linked list of FileList structs. */ UBYTE *Hide; /* Default hide wildcard */ /* Must set FR_HIDEWILD for it to be used */ /* Will contain a copy of the last wildcard */ /* the user set before exiting the FR on exit */ UBYTE *buffer; /* private storage for temp stuff.. don't touch!!!! */ ULONG unused[4]; /* future expansion. Always set to NULL */ }; You can request a specific LeftEdge, TopEdge, Width, and Height by giving a non-zero value in any of the above arguments. However, it is recommended that you do not. The requester will attempt to come back up where it was the last time if you don't give it the FR_AUTOSIZE and/or FR_AUTOPOSITION flags. The default values are: LeftEdge 120 TopEdge 20 Width 400 Height 200 'oktext' is the text that will be shown in the 'OK' gadget. This should be something like "Load" or "Save" or whatever. The string must not be longer than 7 characters or it will be truncated. Make sure that you set the FR_OKTEXT as described above. 'canceltext' is the text that will be shown in the 'Cancel' gadget. This should be something like "No!" or whatever. The string must not be longer than 7 characters or it will be truncated. Make sure that you set the FR_CANCELTEXT as described above. RESULT pointer to fr->fullname if file selected. NULL if FR cancelled or failed. fr->directory selected path fr->filename selected file fr->fullname full path to file (0 length if FR cancelled) fr->pattern last show pattern used fr->extras->Hide last hide pattern used fr->extras->LeftEdge / fr->extras->TopEdge | The FR's left edge, top edge, width and fr->extras->Width | height when it was closed. fr->extras->Height \ BUGS None. EXAMPLE #include "KDBase.h" struct Library *KD_FReqBase, *OpenLibrary(); main() { struct FRequest *fr, *CreateFRequest(); char *file, *NewFReq(); if (KD_FReqBase = OpenLibrary(KLIBNAME,KLIBVERSION)) { if (fr = (struct FRequest *) CreateFRequest()) { fr->reqtitle = (UBYTE *) "FR Test"; if (file = (char *)NewFReq(fr)) puts(file); else puts("Requester Cancelled!"); DeleteFRequest(fr); } CloseLibrary(KD_FReqBase); } } SELECT LIST ----------- The FR can allow the user to select multiple files from multiple directories. To turn on this mode, you must set the FR_SELECTLIST flag in the NewFReq() call. When the NewFReq() call returns, you can check whether or not the user selected multiple files by checking to see if fr->extras->SelectList contains a value. If it is not NULL, then it points to a list of filenames that can be read by using the NextSelectEntry() call described below. This returned list is yours until you free it by either calling NewFReq() again with the same FRequest structure or free the FRequest structure with DeleteFRequest(). Setting the FR_SLSHOWNAMES makes the 'Path/Name' Select List gadget default to 'Name' instead of 'Path'. Read the user doc file, section 'Select List' for details. The following is an example of how to use the Select List mode: struct FRequester *fr, *CreateFRequest(); UBYTE *name, *NextSelectEntry(); if (fr = (struct FRequest *) CreateFRequest()) { fr->reqtitle = (UBYTE *) "Multiple Select FR Test"; fr->flags = FR_STDFLAGS | FR_SELECTLIST; if (NewFReq(fr)) { printf("File : %s\n",fr->fullname); if (fr->extras->SelectList) /* Check if the user selected a */ { /* list of files. */ printf("\nSelect List:\n\n"); /* yes, print them out */ while (entry = NextSelectEntry(fr)) { printf("%s\n",entry); } } } DeleteFRequest(fr); } Notes: - The call returns both a normal file name and a list of files. It is up to the calling program to clarify this point to the user. - Check out the test.c file for the full example on how to use this facility. - The FR_User.DOC file contains all the details on how the user can use the Select List mode. KEEP BUFFERS ------------ If the FR_KEEPBUFFERS flag is set, then the FR will not clear its directory buffers and the next call to NewFReq() with the same FRequest struct will bring up the FR with all the directories intact. This includes all 5 buffers. The FR will also come up with the current buffer being the last one that was used. This means that the FR does not have to re-read the directories again. The DeleteFRequest() call takes care of cleaning up all the buffers associated with this feature. This needs no work from the programmer. Just set the FR_KEEPBUFFERS flag and it will all be handled for you. Just make sure that you don't mind the memory that will be used to store these buffers. Average memory requirements are around 70 files per 2k of memory. Along with this feature, the FlushFRBuffers() call allows the programmer to selectively flush out the directory buffers without hurting anything else in the FRequest structure. EXTRA BUTTON ------------ The ExtraButton feature allows the calling program to define an extra button in the file requester. This button must contain a title with a maximum of 10 characters. You need to provide the following data in an ExtraButton structure: struct ExtraButton { struct ExtraButton *next; /* pointer to next button - NULL for now */ ULONG flags; /* flags to define button - 0 for now */ ULONG (*button_function)(struct ExtraButton *); /* function to be called when button is hit */ UBYTE *text; /* actual text of button, up to 10 chars */ UBYTE *help1, *help2, *help3; /* pointers to help lines - optional */ VOID *UserData; /* for your use... */ struct Window *window; /* current FR window.. read only. */ }; Your function to be called by the FR when the extrabutton is called needs to be formatted like this: ULONG button(eb) struct ExtraButton *eb; { printf("Hey! The user clicked on the extra button!!\n"); printf("Button: %s\n",eb->text); printf("Window: %08x\n",eb->window); return(EB_CONTINUE); } Note that it receives a pointer to the ExtraButton struct on the stack. You can access all the data in the structure, but it is not safe to modify any of it, except the UserData field. When your function returns, it must do so with a return value of one of the following: - EB_CONTINUE The FR just continues as if nothing happened. - EB_OK The FR is OK'd and exists immediately - EB_CANCEL The FR is cancelled and exists immediately The following is a summary of what you need to do to use this feature: 1. Set the FR_EXTRABUTTONS flag. 2. Fill in the fr->extras->buttons with the address of your ExtraButton struct. 3. Fill in the eb.button with the address of the function to call. The test.c file contains a full example of how to use the ExtraButton. Notes: - Make sure you set the eb.next to NULL for now. This will hopefully support multiple buttons in the future. Also set the eb.flags to 0. - The FR waits around for you while you handle the function... so be brief! ------------------------------------------------------------------------------ kd_freq.library/NextSelectEntry NAME NextSelectEntry - Get next file name from FR Select List SYNOPSIS result = NextSelectEntry(fr); D0 A0 struct FRequest *fr; UBYTE *result; FUNCTION Returns the next entry in the Select List file that is created by NewFReq() if the user selects multiple files. The first time this call is used, it returns the first file name in the Select List or NULL if no select list exists. It basically returns the file name pointed to by fr->extras->NextEntry and updates fr->extras->NextEntry to point at the next entry in the list. RESULT Pointer to a string, NULL if failed or reached end of list. BUGS None. EXAMPLE char *filename; filename = NextSelectEntry(); The NewFReq() description above contains a full example of how to use this function. ------------------------------------------------------------------------------ kd_freq.library/CreateFRequest NAME CreateFRequest - Allocate memory for a FRequest structure. SYNOPSIS fr = CreateFRequest(); D0 struct FRequest *fr; FUNCTION Allocates a FRequest structure, an ExtraData struct, a 32 char filename string, a 32 string pattern string, and a 128 char directory string. So, if you get a successful result, you will have the following: fr pointer to an initialized FRequest structure fr->extras pointer to a blank ExtraData structure fr->filename pointer to a 32 char string fr->directory pointer to a 128 char string fr->fullname pointer to a 160 char string (read only) fr->pattern pointer to a 32 char string fr->flags contains STD_FLAGS fr->extras->Hide pointer to a 32 char string It will return a valid pointer to a FRequest only if it can allocate all of the above, otherwise it will fail. It is wiser to use this call to allocate a FRequest struct at the start of your program, and deallocate it using DeleteFRequest() at the end of your program, allowing you to call the FR easily at any time with a simple call. RESULT Pointer to a FRequest structure, NULL if failed. BUGS None. EXAMPLE struct FRequest *fr; fr = CreateFRequest(); ------------------------------------------------------------------------------ kd_freq.library/DeleteFRequest NAME DeleteFRequest - Deallocate a FRequest structure that was initialized with CreateFRequest. SYNOPSIS void DeleteFRequest(fr); A0 struct FRequest *fr; FUNCTION Frees all memory allocated via CreateFRequest(). It will also checks if there is an Extended Select list attached to this FRequest structure, and will free its memory if it exists. RESULT None. BUGS None. EXAMPLE struct FRequest *fr; DeleteFRequest(fr); ------------------------------------------------------------------------------ kd_freq.library/FlushFRBuffers NAME FlushFRBuffers - Frees cached directory buffers SYNOPSIS FlushFRBuffers(fr); A0 struct FRequest *fr; FUNCTION Frees all memory associated with the Keep Buffers features from a FRequest struct without affecting any other entry in it. RESULT None. BUGS None. ------------------------------------------------------------------------------ kd_freq.library/NewPatMatch NAME NewPatMatch - do AmigaDOS style wild card filename pattern matching. SYNOPSIS result = NewPatMatch(pattern,filename); D0 A0 A1 LONG result UBYTE *pattern; UBYTE *filename; FUNCTION Accepts a string that is a valid AmigaDOS file name (filename) and a valid AmigaDOS wild card pattern and tells you whether the filename matches the pattern or not. Supported wildcards in pattern: 1. Standard AmigaDOS Wildcards: -------------------------------- ? Matches any single character #p Match any number of occurences of the pattern p % Matches the null string () Make a group of characters into a single pattern | The OR operator ' Disable wildcard interpretation of next character (unless it is an extended wildcard as shown below.) 2. Extended Wildcards: ----------------------- These are wildcards not supported by the standard AmigaDOS convention, but expand it to make it more versatile. 'd Matches any single digit. (0 to 9) 'a Matches any single alpha character. (a to z) 'n Matches any single alphanumeric character. For examples of standard wildcard usage, look up any AmigaDOS tutorial book. Examples of extended wildcards: Pattern Matching possibilities ------- ---------------------- test'n test0, test1, test9, testa, testA, testz, testZ test'd test0, test1, test9 test'a testa, testA, testz, testZ test 'd test 1, test 2, test 9 test#'d test1, test100, test10234 #'a#'d a1, ab12, abc1, abc123, adks34234 (matches any string with some or no alpha characters, then some or no digits.) #'a'd#'d.c a1.c, a203.c, 100.c, 1.c, adsdfs931234.c (matches any string that starts with some of no alpha characters, then at least 1 or more digits, and ends with .c) RESULT result = -1 Syntax error in wildcard pattern. result = 0 Filename did not match pattern. result = 1 Filename matched pattern. BUGS None. EXAMPLE LONG result; result = NewPatMatch("#?.c","test.c"); This will result in: result == 1 ------------------------------------------------------------------------------ kd_freq.library/NewPath NAME NewPath - expand a file name to its full path. SYNOPSIS New Path(filename); A0 UBYTE *filename; FUNCTION Accepts a string that a valid AmigaDOS file or directory name and expands it to the full path leading to the file/directory name. RESULT filename - full path Note: UBYTE *filename must be least UBYTE [128] in size. e.g. UBYTE filename[128]; The string is terminated with either a / or a : depending on whether it is a valid directory or device. If the filename is not a valid file name, then 'filename' is truncated to 0 length; BUGS None. EXAMPLE UBYTE filename[128] = "dh0:"; NewPath(filename); ------------------------------------------------------------------------------ kd_freq.library/FReq --- OBSOLETE CALL! --- NAME FReq - bring up a file requester and obtain a file name. SYNOPSIS result = FReq(screen,reqtitle,filename,directory,pattern,flags,extras); LONG result struct Screen *screen; UBYTE *reqtitle; UBYTE *filename; UBYTE *directory; UBYTE *pattern; ULONG flags; struct ExtraData *extras; FUNCTION --- OBSOLETE CALL! --- RESULT ------------------------------------------------------------------------------ kd_freq.library/PatMatch --- OBSOLETE CALL! --- NAME PatMatch - do AmigaDOS style wild card filename pattern matching. SYNOPSIS result = PatMatch(pattern,filename); LONG result UBYTE *pattern; UBYTE *filename; FUNCTION --- OBSOLETE CALL! --- RESULT ------------------------------------------------------------------------------ kd_freq.library/Path --- OBSOLETE CALL! --- NAME Path - expand a file name to its full path. SYNOPSIS Path(filename); UBYTE *filename; FUNCTION --- OBSOLETE CALL! --- RESULT ------------------------------------------------------------------------------ If you have any trouble getting any call to work, don't hesitate to email me on Compuserve 75166,2531 or leave me a message in the AmigaTech forum on CIS or mail/fax me at the address at the end of the FR_User.doc file. ------------------------------------------------------------------------------ Copyright 1990,1991 Khalid Aldoseri. 26 Nov 1991. ------------------------------------------------------------------------------